docs: scope client branding (product name + logo to id.ai), session-bound contract - #103

Pull request overview

Adds a scoping/design document defining a proposed “client branding” extension for MCP→Internet Identity authorization, allowing id.ai to show a vetted connector’s product name and logo on the consent screen by using a curated server-side product slug and same-origin endpoints.

Changes:

• Add docs/scoping-client-branding.md describing the proposed contract/flow, vetting model, endpoints, security considerations, and phased rollout plan.

Dynamic client registration is **unauthenticated and open** (`POST /oauth/register` takes all
callers, `auth.rs:1888`). So any client-supplied `client_name` / `logo_uri` is attacker-
controlled. Rendering it on a consent screen would be a phishing gift: a hostile client

  client `logo_uri`. Logos are compiled-in assets (like the DFINITY logo already inlined into the
  callback page via `include_str!`, `auth.rs:1161`).

- Minted fresh per registration: `client-{uuid_v4}` (`auth.rs:1913`), a new random value each
  time anyone registers.

- **Bounded, closed slug space.** Both GETs serve only from the fixed curated set; an unknown slug
  is a `404`. Responses are small, cacheable, and served from compiled-in assets.
- **Logo rendering on II (the one II-side must).** SVG is acceptable as the logo format, but only
  if II renders it through a fixed-size `<img src=...>`. It must never inline server-returned SVG
  into the consent DOM: inlined SVG can execute script, an `<img>`-loaded SVG cannot. (A raster
  logo would sidestep the concern entirely, but `<img>`-rendered SVG is safe and keeps the crisp
  vector mark.)
- **CORS / caching** mirror the `#4091` well-known: `Access-Control-Allow-Origin` for the JSON
  metadata (II uses `fetch`), and `no-store` so an intermediary cannot serve a mapping stale after
  a curation change.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Two decisions frame everything below:

- **Bounded, closed slug space.** Both GETs serve only from the fixed curated set; an unknown slug
  is a `404`. Responses are small, cacheable, and served from compiled-in assets.

Review from the II-side design point of view

Answering §10, since it's addressed to the II team. Grounded in the current II frontend/backend (the id.ai/mcp connect flow, the declared-callback allow-list, and the production CSP).

The identity/trust model is right — no changes needed there

• Curated, server-side product identity, never client-supplied. Correct. II isn't a party to the client↔server OAuth, so anything the client can set (DCR client_name, logo_uri) is unauthenticated and phishable. Deriving identity from the vetted redirect vendor is a sound proxy: II's declared-callback allow-list (fetch of /.well-known/ii-auth-callbacks, fail-closed, exact match) already means a connect can only reach us over an origin that published that manifest, so the vendor is effectively attested by the same mechanism.
• Product slug, not client_id. Correct. The connect link is attacker-craftable and client-{uuid_v4} churns / is LRU-evicted, so a client_id in the fragment would be a spoofable, unstable display key. A closed slug space resolved server-side is the right identifier.
• Additive / backward-compatible contract. Confirmed on our end — the link parser ignores unknown fragment params today, so an added connector is safe for old II, and old servers simply omit it. The only II code cost is one field added to the link schema.

The one real gap: logo transport will hit II's CSP (§10 Q2)

The doc's model — II renders '<img src="{issuer}/branding/{slug}/logo">' pointing at the callback origin — is blocked by II's Content-Security-Policy. This is the main thing to revise.

II's production CSP is:

img-src 'self' data: https://*.googleusercontent.com;
connect-src 'self' https:;

So:

• A cross-origin '<img src="https://<callback-origin>/…/logo">' won't load — img-src allows only 'self', data:, and one fixed Google-avatar host. We don't want to widen img-src to https:, since that reopens exactly the cross-origin image surface we keep closed.
• fetch() to any HTTPS origin is allowed (connect-src 'self' https:).

Recommended contract instead: II fetch()es the branding from the trust-confirmed callback origin and renders the logo as a data: URI (already permitted by img-src data:, no CSP change). Simplest shape: serve one metadata document with the logo inlined as a bounded base64 data: image, so II makes a single request to a single origin and never needs a second cross-origin image hop. That also answers §10 Q4 — one doc with an inline logo beats separate name/logo requests for us.

Note this flips one assumption in the doc: "No CORS needed for <img>" doesn't apply, because we reach the logo via fetch() (which does need the CORS header you already specify) and then render data:.

SVG vs raster (§10 Q2 cont.)

The doc's point that an <img>-loaded SVG can't execute script is technically true. But once II is building a data: URI from fetched bytes, I'd steer away from SVG: it keeps a latent "never inline this" invariant that future contributors won't know, whereas raster (PNG) is strictly safer and removes the question entirely. Recommend the curated logos be PNG, with II applying a raster-only content-type allow-list, a byte-size cap, a decode step, and a fail-closed fallback to the anonymous icon on any validation failure — i.e. apply the same hardening the doc reserves for a hypothetical Phase-3 open path, in v1, because II is the side putting bytes on screen.

Trust ordering — please state it explicitly

connector={slug} lives in the fragment, which is attacker-craftable (a malicious link can claim &connector=claude). Safety comes entirely from where II fetches branding: only from the callback origin, and only after that origin is trust-confirmed — i.e. after the certified trusted_url gate confirms the server origin, and after the callback is matched against the origin's declared allow-list. The slug is display-only routing; the authority for "is this really ChatGPT" is that the branding came from an origin II independently trust-confirmed, never the fragment's claimed value. Worth spelling out so the II implementation doesn't fetch branding on the honest-untrusted / unverified path.

§10, point by point

1. Fragment param + endpoint paths — connector={slug} is fine (additive; parser ignores unknowns). Prefer a single metadata endpoint with an inline logo over a separate /logo route.
2. Render logo via fixed-size '<img src=…>'? Not cross-origin (CSP blocks it). Yes via fetch() + data:, or an inline base64 data: logo in the JSON — and please make it raster, not SVG.
3. "Verified connector" treatment + name delivery — deliver the name in the JSON, not mirrored in the fragment (fragment is untrusted; JSON comes from the trust-confirmed origin). The exact verified-vs-anonymous consent UI is ours to specify and I'll take it to the II design owners; the security contract we need from the server is: branding is shown ⇔ trust-confirmed origin + declared callback + valid slug + valid logo; otherwise fall back to the anonymous screen.
4. Single doc vs. separate requests — single metadata document with the logo inlined as base64 data:. One request, one origin, no CSP friction.

Minor

• Security section is solid: no client-supplied content, no SSRF in v1 (logos bundled at build time), closed slug space with 404 otherwise. If the Phase-3 open self-service path is ever built, the SSRF-pinned client + https-only + size/dimension caps + raster-only + decode-then-re-encode is exactly right — but the rendering hardening (size cap / raster / fail-closed) should be II-side and present from v1, not deferred.
• Keeping native/desktop (loopback-redirect) connectors anonymous until a signed software_statement is the correct v1 cut — those are exempt from the callback allow-list, so there's no vetted-vendor anchor to derive identity from.

Bottom line: the trust model needs no changes. The one substantive revision is the logo transport — replace "II renders a cross-origin <img src>" with "II fetches from the trust-confirmed origin (or reads an inline base64 logo from the metadata JSON) and renders a data: raster image, failing closed to the anonymous screen." That's the only part that breaks on contact with II's CSP.

Generated by Claude Code